<?php
/**
 * Kernel of the system. Main crossroad and entry point, loader, etc... the
 * hearth of the CMS.
 *
 * @author Martin "DevelX" Jurča
 * @version 2008-02-13
 */
interface Kernel {
    /**
     * Constant representing public web display mode of the CMS. In this mode
     * the system is set for displaying public web page interface.
     */
    const DISPLAY = 0;

    /**
     * Constant representing display admin UI mode of the CMS. In this mode
     * the system is set for displaying administration interface.
     */
    const ADMIN = 1;

    /**
     * Constant representeing event mode of the CMS. In this mode the
     * system is set for processing external events. System switched
     * automatically to display or display admin mode after finishing this
     * mode.
     */
    const EVENT = 2;

    /**
     * Constructor is private so noone will try to create an instance of
     * Kernel class. All methods are static so no instance is required.
     */
    private function __construct();

    /**
     * The initialization method of Kernel and whole CMS. This method
     * initializates the basic elements and calls one of more-specified init
     * methods according to http request properties. Also check whether the
     * system has been installed.
     *
     * @return boolean True if the CMS finished successfuly, otherwise
     *         false.
     */
    public static function init();

    /**
     * Initializates system instalation process and guides the administrator
     * through initial settings.
     *
     * @return boolean True if the mode has finished successfully, false
     *         otherwise.
     */
    private static function initInstall();

    /**
     * Performs further initializations of enviroment for displaying public
     * web site. When initialization is done the displaying is manadged by
     * system module View Controller. This is the default mode.
     *
     * @return boolean True if the mode has finished successfully, false
     *         otherwise.
     */
    private static function initDisplay();

    /**
     * Performs further initializations of enviroment for displaying
     * administration interface. When initialization is done the displaying is
     * manadged by system module View Controller. During initialization the
     * kernel performs autentication and authorisation of the user.
     * To enter this mode, set http request field (GET or POST data) mode to
     * value 'admin' (normally done by url parsing, public url begin with
     * /admin/).
     *
     * @return boolean True if the mode has finished successfully, false
     *         otherwise.
     */
    private static function initAdmin();

    /**
     * Performs further initializations of enviroment for delivering external
     * events to modules. There is no output during this mode and all data
     * are processed internally. To enter this mode, set https request field
     * (GET or POST data) mode to value 'event'. After finishing this mode the
     * system enters either display or display admin mode.
     *
     * @return boolean True if the mode has finished successfully, false
     *         otherwise.
     */
    private static function initEvent();

    /**
     * Sets language for this session. Language should be specified with the
     * same language code as is used in Accept-Language HTTP header.
     * The setLanguage affects all localized labels in the both public and
     * administration interface.
     * When requested language is not available for some component, this
     * component uses more general variation of requested language, e.g. if
     * requested language is en_US and the component is not localized for
     * en_US, the component should use en. If this generalized variation of
     * requested language is not available either, default language set in
     * system configuration should be used. If even this language is not
     * available the component is free to use any available language.
     *
     * @param String $language Language code of language to be used in the
     *        user interface.
     * @return boolean True on success, false otherwise.
     */
    public static function setLanguage($language);

    /**
     * Returns code of primary language set for this session. If session
     * language has not been set yet the method returns system default
     * language.
     *
     * @return String Currently used language for session.
     */
    public static function getLanguage();

    /**
     * Changes output charset for current session.
     *
     * @param String $charset Output charset to be used.
     * @return boolean True on success, false otherwise.
     */
    public static function setCharset($charset);

    /**
     * Returns output charset used for current session.
     *
     * @return String Output charset used for current session.
     */
    public static function getCharset();

    /**
     * Returns one of Kernel::DISPLAY, Kernel::ADMIN and Kernel::EVENT
     * representing current mode of the system.
     *
     * @return int One of Kernel::DISPLAY, Kernel::DISPLAY and
     *         Kernel::EVENT representing current mode of the system.
     */
    public static function getMode();

    /**
     * Returns true if page is being displayed in AJAX mode. In this mode is
     * only one given fragment displayed and everything else is ommited. To run
     * system in AJAX mode, set the HTTP request field (GET or POST data) ajax
     * to true.
     *
     * @return boolean True if page is being displayd in AJAX mode, false
     *         otherwise.
     */
    public static function isAJAXMode();

    /**
     * Parses the given string and removes all non-ASCII characters with the
     * closes ASCII characters, replaces all incomplatible characters and
     * spaces with dashes and removes additional dashes from the prefix and
     * the suffix.
     *
     * @param String $rawString Raw string to be parsed into url-compatible
     *        form.
     * @return String Url-compatible string similliar to the given raw string.
     */
    public static function createUrl($rawString);

    /**
     * Returns link to image displaying utility with attached parameters for
     * image manipulator to get desired result. This link may be used as value
     * of img (X)HTML element attribute src.
     *
     * @param Array $parameters Parameters for image manipulator.
     * @return String URL to image rendering utility with parsed parameters.
     */
    public static function getImageLink(&$parameters);

    /**
     * Available only in event mode. Sets location where the client should be
     * automatically redirected. If not set, the system enter display or admin
     * mode - to enter admin mode, inAdmin field of GET or POST data has to be
     * set.
     *
     * @param String $url URL where to redirect client.
     */
    public static function setRedirect($url);
}
?>
